[Boto3 Adv-Cal DAY20]boto3をdoxygenで可視化してみた

boto3 で楽しむ AWS PythonLife 一人AdventCalendarです。

boto3のドキュメントを通して、サービス別にどういった事が出来るのかを理解したり、管理コンソールを通さずにTerminalだけで完結できるように検証していくことが目的になります。

20日目はboto3をDoxygenでの可視化にチャレンジしてみました。

目次

• Doxygenについて
• Boto3のドキュメントを生成する
  • Doxygenのインストール
  • MacTexのインストール
  • 設定ファイルの作成
  • 設定項目の変更
  • PDF化
• ドキュメントの観覧
  • HTML
  • PDF
• まとめ

Doxygenについて

http://www.doxygen.jp/

ソースコードのドキュメンテーションツールです。Doxygenで実際に生成されたドキュメント例も公式でまとめられています。

Example of output generated by doxygen

Boto3のドキュメントを生成する

Doxygenを使って実際にドキュメントを作成していきます。

Doxygenのインストール

Homebrew経由です。

% brew update
% brew install doxygen

MacTexのインストール

PDF生成手段として、LatexのOSX版MacTexを導入します。

MacTEX

brew install caskroom/cask/brew-cask
brew cask install mactex

MacTexのダウンロードにはそれなりの時間がかかるため、余裕を持って行いましょう。

設定ファイルの作成

既存のファイルと被らないようにします。

% git clone git@github.com:boto/boto3.git
% cd boto3
% doxygen -g reference

設定項目の変更

いくつもの項目がありますが、

• 再帰の取得
• プライベートメンバーの取得

の2点を今回は重視しました。

% vim reference
..
CREATE_SUBDIRS         = YES
..
EXTRACT_ALL            = YES
..
EXTRACT_PRIVATE        = YES
..
EXTRACT_PACKAGE        = YES
..
EXTRACT_STATIC         = YES
..
RECURSIVE              = YES
..
% doxygen reference

PDF化

doxygenコマンド実行後に、latexフォルダで行います。

% cd latex
% make

正常に完了した場合、refman.pdfという240ページ程のファイルが生成されているはずです。

ドキュメントの観覧

HTMLとPDFでそれぞれ生成されているはずです。

HTML

% open html/index.html

PDF

% open latex/refman.pdf

まとめ

各サービス毎の呼び出し方法についてはboto3の公式ドキュメントを触る方が早いのですが、boto3そのものの実装を辿る場合等にはDoxygenで生成したドキュメントが役立ちます。

依存しているbotocoreについても、今回と同じような手続きでドキュメント化が可能です。

boto3の更新頻度自体がそこそこ高いのため、必要であればリポジトリそのものをWatchして、更新通知毎に自動ビルドすることをおすすめします。